<!doctype html>


<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>query.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
     var _typeTreeName = "goog";
     var _fileTreeName = "Source";
  </script>

  <script src="static/js/doc.js">
  </script>


  <meta charset="utf8">
</head>

<body onload="grokdoc.onLoad();">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>





<div class="colmask rightmenu">
<div class="colleft">
    <div class="col1">
      <!-- Column 1 start -->

<div id="title">
       <span class="fn">query.js</span>
</div>

<div class="g-section g-tpl-75-25">
  <div class="g-unit g-first" id="description">
    This code was ported from the Dojo Toolkit
 <a href="http://dojotoolkit.org">http://dojotoolkit.org</a> and modified slightly for Closure.

 goog.dom.query is a relatively full-featured CSS3 query function. It is
 designed to take any valid CSS3 selector and return the nodes matching
 the selector. To do this quickly, it processes queries in several
 steps, applying caching where profitable.
 The steps (roughly in reverse order of the way they appear in the code):
 1.) check to see if we already have a "query dispatcher"
 - if so, use that with the given parameterization. Skip to step 4.
 2.) attempt to determine which branch to dispatch the query to:
 - JS (optimized DOM iteration)
 - native (FF3.1, Safari 3.2+, Chrome, some IE 8 doctypes). If native,
 skip to step 4, using a stub dispatcher for QSA queries.
 3.) tokenize and convert to executable "query dispatcher"
 assembled as a chain of "yes/no" test functions pertaining to
 a section of a simple query statement (".blah:nth-child(odd)"
 but not "div div", which is 2 simple statements).
 4.) the resulting query dispatcher is called in the passed scope
 (by default the top-level document)
 - for DOM queries, this results in a recursive, top-down
 evaluation of nodes based on each simple query section
 - querySelectorAll is used instead of DOM where possible. If a query
 fails in this mode, it is re-run against the DOM evaluator and all
 future queries using the same selector evaluate against the DOM branch
 too.
 5.) matched nodes are pruned to ensure they are unique
  </div>
  

        <div class="g-unit" id="useful-links">
          <div class="title">Useful links</div>
          <ol>
            <li><a href="closure_third_party_closure_goog_dojo_dom_query.js.source.html"><span class='source-code-link'>Source Code</span></a></li>
            <li><a href="http://code.google.com/p/closure-library/source/browse/closure/third_party/closure/goog/dojo/dom/query.js">Git</a></li>
          </ol>
        </div>
</div>

<h2 class="g-first">File Location</h2>
  <div class="g-section g-tpl-20-80">
    <div class="g-unit g-first">
      <div class="g-c-cell code-label">_party/closure/goog/dojo/dom/query.js</div>
    </div>
  </div>
<hr/>


   
<br/>

  <div class="legend">
        <span class="key publickey"></span><span>Public</span>
        <span class="key protectedkey"></span><span>Protected</span>
        <span class="key privatekey"></span><span>Private</span>
  </div>









<div class="section">
  <table class="horiz-rule">


  </table>
</div>




  <h2>Global Functions</h2>





<div class="section">
  <table class="horiz-rule">


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.dom.query"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.dom.</span><span class="entryName">query<span class="args">(<span class="arg">query</span>,&nbsp;<span class="arg">opt_root</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type">{length: number}</span></div>
      </div>


     <div class="entryOverview">
       Returns nodes which match the given CSS3 selector, searching the
entire document by default but optionally taking a node to scope
the search by.

dojo.query() is the swiss army knife of DOM node manipulation in
Dojo. Much like Prototype's "$$" (bling-bling) function or JQuery's
"$" function, dojo.query provides robust, high-performance
CSS-based node selector support with the option of scoping searches
to a particular sub-tree of a document.

Supported Selectors:
--------------------

dojo.query() supports a rich set of CSS3 selectors, including:

class selectors (e.g., `.foo`)
node type selectors like `span`
` ` descendant selectors
`&gt;` child element selectors
`#foo` style ID selectors
`*` universal selector
`~`, the immediately preceded-by sibling selector
`+`, the preceded-by sibling selector
attribute queries:
|  * `[foo]` attribute presence selector
|  * `[foo='bar']` attribute value exact match
|  * `[foo~='bar']` attribute value list item match
|  * `[foo^='bar']` attribute start match
|  * `[foo$='bar']` attribute end match
|  * `[foo*='bar']` attribute substring match
`:first-child`, `:last-child` positional selectors
`:empty` content empty selector
`:empty` content empty selector
`:nth-child(n)`, `:nth-child(2n+1)` style positional calculations
`:nth-child(even)`, `:nth-child(odd)` positional selectors
`:not(...)` negation pseudo selectors

Any legal combination of these selectors will work with
`dojo.query()`, including compound selectors ("," delimited).
Very complex and useful searches can be constructed with this
palette of selectors.

Unsupported Selectors:
----------------------

While dojo.query handles many CSS3 selectors, some fall outside of
what's reasonable for a programmatic node querying engine to
handle. Currently unsupported selectors include:

namespace-differentiated selectors of any form
all `::` pseudo-element selectors
certain pseudo-selectors which don't get a lot of day-to-day use:
|  * `:root`, `:lang()`, `:target`, `:focus`
all visual and state selectors:
|  * `:root`, `:active`, `:hover`, `:visited`, `:link`,
`:enabled`, `:disabled`, `:checked`
`:*-of-type` pseudo selectors

dojo.query and XML Documents:
-----------------------------

`dojo.query` currently only supports searching XML documents
whose tags and attributes are 100% lower-case. This is a known
limitation and will [be addressed soon]
(<a href="http://trac.dojotoolkit.org/ticket/3866">http://trac.dojotoolkit.org/ticket/3866</a>)

Non-selector Queries:
---------------------

If something other than a String is passed for the query,
`dojo.query` will return a new array constructed from
that parameter alone and all further processing will stop. This
means that if you have a reference to a node or array or nodes, you
can quickly construct a new array of nodes from the original by
calling `dojo.query(node)` or `dojo.query(array)`.

example:
search the entire document for elements with the class "foo":
|  dojo.query(".foo");
these elements will match:
|  <span class="foo"></span>
|  <span class="foo bar"></span>
|  <p class="thud foo"></p>
example:
search the entire document for elements with the classes "foo" *and*
"bar":
|  dojo.query(".foo.bar");
these elements will match:
|  <span class="foo bar"></span>
while these will not:
|  <span class="foo"></span>
|  <p class="thud foo"></p>
example:
find `<span>` elements which are descendants of paragraphs and
which have a "highlighted" class:
|  dojo.query("p span.highlighted");
the innermost span in this fragment matches:
|  <p class="foo">
|    <span>...
|      <span class="highlighted foo bar">...</span>
|    </span>
|  </p>
example:
find all odd table rows inside of the table
`#tabular_data`, using the `&gt;` (direct child) selector to avoid
affecting any nested tables:
|  dojo.query("#tabular_data &gt; tbody &gt; tr:nth-child(odd)");</span>
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">query</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a></span><span>&nbsp;|&nbsp;</span><span class="type">null</span><span>&nbsp;|&nbsp;</span><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>)</div>
        <div class="entryOverview">The CSS3 expression to match against. For details on the syntax of CSS3 selectors, see <a href="http://www.w3.org/TR/css3-selectors/#selectors">http://www.w3.org/TR/css3-selectors/#selectors</a>.</div>
     </td>
   </tr>
     
   <tr class="odd">
     <td>
        <span class="entryName">opt_root</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/DOM/Node">Node</a></span><span>&nbsp;|&nbsp;</span><span class="type">null</span><span>&nbsp;|&nbsp;</span><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span><span>&nbsp;|&nbsp;</span><span class="type">undefined</span>)</div>
        <div class="entryOverview">A Node (or node id) to scope the search from (optional).</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type">{length: number}</span></div>&nbsp;
            The elements that matched the query.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_third_party_closure_goog_dojo_dom_query.js.source.html#line193">code &raquo;</a>
  </td>
     </tr>


  </table>
</div>






      <!-- Column 1 end -->
    </div>

        <div class="col2">
          <!-- Column 2 start -->
          <div class="col2-c">
            <h2 id="ref-head">Directory dom</h2>
            <div id="localView"></div>
          </div>

          <div class="col2-c">
            <h2 id="ref-head">File Reference</h2>
            <div id="sideFileIndex" rootPath="" current="_party/closure/goog/dojo/dom/query.js"></div>
          </div>
          <!-- Column 2 end -->
        </div>
</div>
</div>

</body>
</html>
